feat(cli): add --mode options to diff command. deprecates --change-set/--no-changeset #32830

msessa · 2025-01-10T03:05:31Z

Issue # (if applicable)

Reason for this change

The current behaviour of implicitly reverting to template-only diff can hide important error messages from the user that can help catching mistakes early before deployment.

This is especially true when a template uses transforms or when using changeset-level cloudformation hooks to enforce compliance rules.

See an example code snippet at the bottom

Description of changes

Added a --mode option to the diff command that replaces (deprecates) --change-set/--no-changeset.

The following modes are supported:

auto : Attempts changeset creation and fallback to local mode should any error be encountered. (replaces -change-set)
change-set: Attempts changeset creation but doesn't handle errors returned by cloudformation when creating a changeset for an existing stack. Instead those errors are surfaced to the user
template-only: Uses template-only diff (replaces --no-change-set)

Description of how you validated changes

Added unit test
Added integration test
Tested against the example code at the bottom

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

Example Code

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';

const app = new cdk.App();

export class TestStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Deploy first without this resource, then add and diff
    new cdk.CfnOutput(this, 'TestOutput', {
      value: cdk.Fn.transform('MyTransform', { Param: "Value"}).toString()
    })
  }
}

new TestStack(app, 'MyTestStack');

app.synth()

Current behaviour on diff:

$ npx cdk diff MyTestStack
Hold on while we create a read-only change set to get a diff with accurate replacement information (use --no-change-set to use a less accurate but faster template-only diff)
Could not create a change set, will base the diff on template differences (run again with -v to see the reason)
Stack MyTestStack
Outputs
[+] Output TestOutput TestOutput: {"Value":{"Fn::Transform":{"Name":"MyTransform","Parameters":{"Param":"Value"}}}}

New behaviour on diff:

$ npx cdk diff --no-fallback MyTestStack
Hold on while we create a read-only change set to get a diff with accurate replacement information (use --no-change-set to use a less accurate but faster template-only diff)
Failed to create ChangeSet cdk-diff-change-set on MyTestStack: FAILED, No transform named 000000000000::MyTransform found.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

aws-cdk-automation

The pull request linter fails with the following errors:

❌ Features must contain a change to an integration test file and the resulting snapshot.
❌ CLI code has changed. A maintainer must run the code through the testing pipeline (git fetch origin pull/32830/head && git push -f origin FETCH_HEAD:test-main-pipeline), then add the 'pr-linter/cli-integ-tested' label when the pipeline succeeds.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

msessa · 2025-01-10T14:04:28Z

Clarification Request: Integration test has been added but the linter still doesn't seems too happy. Anything I can do about that?

mrgrain

Thanks for getting started on this!

In stead of introducing a new boolean option that only sometimes has an effect, we should create a new 3-way switch option to replace the current --change-set and --no-change-set options.

Something like

--mode=auto
--mode=change-set
--mode=template-only

msessa · 2025-01-14T01:42:32Z

@mrgrain I have addressed your feedback. Let me know what you reckon

aws-cdk-automation · 2025-01-15T23:56:23Z

AWS CodeBuild CI Report

CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
Commit ID: ea60fe6
Result: SUCCEEDED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

aws-cdk-automation · 2025-02-02T00:13:37Z

This PR cannot be merged because it has conflicts. Please resolve them. The PR will be considered stale and closed if it remains in an unmergeable state.

aws-cdk-automation · 2025-02-03T00:12:27Z

This PR has been in the CHANGES REQUESTED state for 3 weeks, and looks abandoned. To keep this PR from being closed, please continue work on it. If not, it will automatically be closed in a week.

mrgrain · 2025-02-03T12:22:53Z

@msessa FYI, we've parked this to prioritize some other work in the CLI area. I'll be getting back it end of February. Apologies for the delay.

mrgrain · 2025-04-09T08:21:49Z

Apologies for the delay and lack of update. This is still on our list but needs to be pushed back further. Will give another update in May.

The primary motivation for this PR is https://github.com/aws/aws-cdk/issues/28753 and the ensuing PR aws/aws-cdk#32830. When implementing diff in the programmatic toolkit library we included the diff method options, and this PR adds the `fallBackToTemplate` property to the `ChangeSet` mode. The idea is that people can specify `fallBackToTemplate=false` to explicitly fail if we cannot successfully create the changeset. The current behavior is to fallback to the template-only method. --- By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

mrgrain · 2025-10-22T14:53:20Z

Hi @msessa apologies, this really slipped off my plate. The cli repo and toolkit-lib are now in a good state to take contributions again. You can find the repo here: https://github.com/aws/aws-cdk-cli

If you are still interested, feel free to re-create the PR on the cli repo. We will then review and handle it over there. Otherwise I have re-opened and transferred the original issue over to the new repo and we are tracking and prioritizing it accordingly.

github-actions · 2025-10-22T14:53:42Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

msessa requested a review from a team as a code owner January 10, 2025 03:05

aws-cdk-automation requested a review from a team January 10, 2025 03:05

github-actions bot added bug This issue is a bug. effort/medium Medium work item – several days of effort p2 beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK labels Jan 10, 2025

msessa had a problem deploying to test-pipeline January 10, 2025 03:06 — with GitHub Actions Failure

aws-cdk-automation requested changes Jan 10, 2025

View reviewed changes

aws-cdk-automation added the pr/needs-cli-test-run This PR needs CLI tests run against it. label Jan 10, 2025

msessa had a problem deploying to test-pipeline January 10, 2025 03:16 — with GitHub Actions Failure

msessa had a problem deploying to test-pipeline January 10, 2025 13:50 — with GitHub Actions Failure

msessa force-pushed the feat/cli-diff-no-fallback branch from 0a38fbc to c0bf4db Compare January 10, 2025 13:51

msessa had a problem deploying to test-pipeline January 10, 2025 13:52 — with GitHub Actions Failure

aws-cdk-automation added pr/reviewer-clarification-requested The contributor has requested clarification on feedback, a failing build, or a failing PR Linter run pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. labels Jan 10, 2025

msessa force-pushed the feat/cli-diff-no-fallback branch from c0bf4db to 8e9f761 Compare January 11, 2025 01:28

msessa had a problem deploying to test-pipeline January 11, 2025 01:29 — with GitHub Actions Failure

mrgrain requested changes Jan 12, 2025

View reviewed changes

msessa force-pushed the feat/cli-diff-no-fallback branch from 8e9f761 to e7a536b Compare January 12, 2025 22:34

msessa had a problem deploying to test-pipeline January 12, 2025 22:35 — with GitHub Actions Failure

aws-cdk-automation removed the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Jan 12, 2025

msessa added 3 commits January 14, 2025 11:16

feat(cli): add --no-fallback options to disable template-only diffs

dfb11b0

chore: document flag in README

0d26798

chore: add integration test

95be843

msessa force-pushed the feat/cli-diff-no-fallback branch from e7a536b to 95be843 Compare January 14, 2025 00:16

feat: replace --no-fallback option with --mode switch

7a8dc32

msessa changed the title ~~feat(cli): add --no-fallback options to disable template-only diffs~~ feat(cli): add --mode options to diff command. deprecates --change-set/--no-changeset Jan 14, 2025

msessa had a problem deploying to test-pipeline January 14, 2025 01:38 — with GitHub Actions Failure

chore: rename local to template-only

01ac49e

msessa had a problem deploying to test-pipeline January 14, 2025 06:05 — with GitHub Actions Failure

Merge branch 'main' into feat/cli-diff-no-fallback

0dbeff1

msessa had a problem deploying to test-pipeline January 14, 2025 06:07 — with GitHub Actions Failure

chore: rename local to template-only in integration test

4637127

msessa had a problem deploying to test-pipeline January 14, 2025 06:08 — with GitHub Actions Failure

chore: restore default value of change-set option

a576887

msessa had a problem deploying to test-pipeline January 14, 2025 06:11 — with GitHub Actions Failure

chore: clean up more old references to local mode

ba9218a

msessa had a problem deploying to test-pipeline January 14, 2025 06:13 — with GitHub Actions Failure

msessa requested a review from mrgrain January 15, 2025 04:15

Merge branch 'main' into feat/cli-diff-no-fallback

ea60fe6

msessa had a problem deploying to test-pipeline January 15, 2025 23:25 — with GitHub Actions Failure

samson-keung added the cli Issues related to the CDK CLI label Jan 23, 2025

github-actions bot mentioned this pull request Feb 1, 2025

Monthly PR metrics report #33266

Closed

mrgrain self-assigned this Feb 3, 2025

mrgrain added the pr-linter/do-not-close The PR linter will not close this PR while this label is present label Feb 3, 2025

mrgrain marked this pull request as draft April 9, 2025 08:20

kaizencc mentioned this pull request Apr 10, 2025

feat(toolkit-lib): fallBackToTemplate option for diffs aws/aws-cdk-cli#354

Merged

mrgrain closed this Oct 22, 2025

github-actions bot locked as resolved and limited conversation to collaborators Oct 22, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(cli): add --mode options to diff command. deprecates --change-set/--no-changeset #32830

feat(cli): add --mode options to diff command. deprecates --change-set/--no-changeset #32830

msessa commented Jan 10, 2025 •

edited

Loading

Uh oh!

aws-cdk-automation left a comment •

edited

Loading

Uh oh!

msessa commented Jan 10, 2025

Uh oh!

mrgrain left a comment •

edited

Loading

Uh oh!

msessa commented Jan 14, 2025

Uh oh!

aws-cdk-automation commented Jan 15, 2025

Uh oh!

aws-cdk-automation commented Feb 2, 2025

Uh oh!

aws-cdk-automation commented Feb 3, 2025

Uh oh!

mrgrain commented Feb 3, 2025

Uh oh!

mrgrain commented Apr 9, 2025

Uh oh!

mrgrain commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(cli): add --mode options to diff command. deprecates --change-set/--no-changeset #32830

feat(cli): add --mode options to diff command. deprecates --change-set/--no-changeset #32830

Conversation

msessa commented Jan 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue # (if applicable)

Reason for this change

Description of changes

Description of how you validated changes

Checklist

Example Code

Uh oh!

aws-cdk-automation left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msessa commented Jan 10, 2025

Uh oh!

mrgrain left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msessa commented Jan 14, 2025

Uh oh!

aws-cdk-automation commented Jan 15, 2025

AWS CodeBuild CI Report

Uh oh!

aws-cdk-automation commented Feb 2, 2025

Uh oh!

aws-cdk-automation commented Feb 3, 2025

Uh oh!

mrgrain commented Feb 3, 2025

Uh oh!

mrgrain commented Apr 9, 2025

Uh oh!

mrgrain commented Oct 22, 2025

Uh oh!

github-actions bot commented Oct 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

msessa commented Jan 10, 2025 •

edited

Loading

aws-cdk-automation left a comment •

edited

Loading

mrgrain left a comment •

edited

Loading